#-*- coding: utf-8 -*-

#This file is part of pyLot library.
#
# pyLot is free software: you can redistribute it and/or modify
# it under the terms of the GNU Lesser General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# pyLot is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU Lesser General Public License for more details.
#
# You should have received a copy of the GNU Lesser General Public License
# along with pyLot.  If not, see <http://www.gnu.org/licenses/>.

__author__ = u'Pierre Puiseux, Guillaume Baty'
__copyright__ = u"Copyright 2011-2012 (C) andheo, Université de Pau et des Pays de l'Adour"
__credits__ = [u'Pierre Puiseux', u'Guillaume Baty']
__license__ = "GNU Lesser General Public License"

__all__ = [u'IBaseHandler']

from traits.api import Interface, Unicode, Python, Str

class IBaseHandler(Interface):
  u"""
  Interface for script application.
  A script application can load and save parameters, switch access level and
  can be translated.
  
  An application is generally used to
   - encapsulate a low level library in a high level class.
   - ease communication between GUI/CLI and low level library
   - process all non GUI treatments
   - catch low level exceptions and solve them or raise user-oriented exceptions instead
  """

  """Unique identifier. You should use convention "module.interface.name" 
  For example 'pyLot.handler.calculator' """
  identifier = Str

  level = Unicode # Current user level. Default: user
  current_locale = Python
  i18n_dir = Unicode

  def translate(self, locale=None, force=False, recursive=True):
    u"""
    Translate dynamically all strings to locale.
    Dynamically means it is not necessary to recreate object to see effects.
    
    if force is False, do not translate again if lang has not changed.
    example :
    
    .. code-block :: python
    
      handler.translate(u'fr_FR') # Translate in french
      handler.translate(u'fr_FR') # Do nothing, handler is yet in french
      handler.translate(u'fr_FR', force=True) # Translate in french again
    
    recursive parameter is used if current handler has IBaseHandler children.
    If recursive is True, call children translate method else, translate only
    this handler. 
    """

  def switchUserLevel(self, level=u'user', force=False, recursive=True):
    u"""
    Switch dynamically the user level.
    Dynamically means it is not necessary to recreate object to see effects.
    
    Implementation must support at least level u'user'.
    Other possible levels are defined by application developer.
    In general, you find levels user/advanced or user/advanced/expert
    but you can imagine what you want (access restriction, thematic, etc.)

    :param level: The level you want to reach
    :type level: :obj:`unicode`
    """

  def writeSettings(self, userconf_dir, recursive=True):
    u"""
    """

  def readSettings(self, userconf_dir, recursive=True):
    u"""
    """

  def append(self, child):
    u"""
    Add a child (object of same type). 
    This child can be reached using children method
    """

  def init(self):
    u"""
    Method called after initialisation.
    """

  def readyToClose(self):
    u"""
    Method called when application is closed.
    If IBaseHandler can be safely closed (ie, is ready to be closed), 
    method returns True, else False.
    
    Handlers typically use this function to check whether the user's work has 
    been saved. While changes are not saved (state is "dirty"), readyToClose
    returns false. If user save changes or discard them, calling a 
    "save" or "clear" method for example, state passes to "clean" and
    readyToClose returns True ... until new user changes. 
    """

  def __iter__(self):
    """
    Return objects appended by append method
    """


if __name__ == '__main__' :
  pass
